docs: add alpha, beta, preview, legacy availability values#5130
docs: add alpha, beta, preview, legacy availability values#5130Swimburger wants to merge 4 commits intomainfrom
Conversation
Document the newly supported x-fern-availability / availability values for OpenAPI endpoints and Fern Definitions: alpha, preview, legacy. Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| ## Endpoints, types, and properties | ||
|
|
||
| Availability can be: | ||
| - `alpha` which means it is an early experimental release; will show an `Alpha` tag |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'it's' instead of 'it is'.
| - `in-development` which means it is being worked on; will show a `Beta` tag | ||
| - `pre-release` which means it is available; will show a `Beta` tag | ||
| - `deprecated` which means it will be removed in the future; will show a `Deprecated` tag | ||
| - `preview` which means it is feature-complete but subject to change; will show a `Preview` tag |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'it's' instead of 'it is'.
| - `deprecated` which means it will be removed in the future; will show a `Deprecated` tag | ||
| - `preview` which means it is feature-complete but subject to change; will show a `Preview` tag | ||
| - `generally-available` which means it is stable and available for use; will show a `GA` tag | ||
| - `deprecated` which means it will be removed in the future; will show a `Deprecated` tag |
There was a problem hiding this comment.
[FernStyles.Current] Avoid time-relative terms like 'in the future' that become outdated
|
🌿 Preview your docs: https://fern-preview-devin-1776986455-add-alpha-preview-legacy-availab.docs.buildwithfern.com/learn Here are the markdown pages you've updated: |
| | `pre-release` | Available | `Beta` | | ||
| | `preview` | Feature-complete but subject to change | `Preview` | | ||
| | `generally-available` | Stable and available for use | `GA` | | ||
| | `deprecated` | Will be removed in the future | `Deprecated` | |
There was a problem hiding this comment.
[FernStyles.Current] Avoid time-relative terms like 'in the future' that become outdated
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
Self-reviewDiff is small and the docs match what's actually shipping in fern#15320 + fern-platform#10027.
This PR can land independently — it's just docs and the values it describes are valid the moment fern#15320 ships. |
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
devin-ai-integration
Bot
changed the title
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
| @@ -1,4 +1,4 @@ | |||
| You can set the availability for the entire API reference or for specific sections in your `docs.yml` configuration. Options are: `stable`, `generally-available`, `in-development`, `pre-release`, `deprecated`, or `beta`. | |||
| You can set the availability for the entire API reference or for specific sections in your `docs.yml` configuration. Options are: `stable`, `generally-available`, `in-development`, `pre-release`, `deprecated`, `alpha`, `beta`, `preview`, or `legacy`. | |||
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[FernStyles.Reject] Use 'API Reference' instead of 'API reference'.
Self-review #2Both reference pages now use a
CI green (3/3). No issues found. |
2 participants
Summary
Documents
alpha,beta,preview, andlegacyas validx-fern-availability/availabilityvalues, alongside the existingin-development,pre-release,generally-available, anddeprecated. Also promotesbetafrom an OpenAPI-only alias forpre-releaseto a first-class value usable in Fern Definitions (matching the change in fern#15320).The pages at
/learn/api-definitions/openapi/extensions/availabilityand/learn/api-definitions/fern-definition/availabilitynow list these values with brief descriptions of each lifecycle stage and the badge they render as.Review & Testing Checklist for Human
Alpha,Beta,Preview,Legacy) match what fern-platform actually renders once fern-platform#10027 and fern#15320 ship.Notes
This PR is purely docs — no functional code changes. The runtime support comes from fern#15320 (CLI / IR / parsers) and fern-platform#10027 (FDR schema + UI). Until those merge, customers writing
availability: alpha|preview|legacyin a Fern Definition orx-fern-availability: alpha|preview|legacyin OpenAPI will be rejected by validation.Link to Devin session: https://app.devin.ai/sessions/dfd46458269a401d82862980e905e9a2
Requested by: @Swimburger